run

重點整理：

這裡講解了 turbo run 指令的用法，該指令用於在 Turborepo 中執行 turbo.json 中指定的任務。它支援多個選項來控制任務的執行行為，並且可以傳遞參數給具體的任務。以下是主要的重點：

1. 指令基本格式

turbo run [tasks] [options] [-- [args passed to tasks]]

• tasks：可以一次執行多個任務，這些任務必須在 turbo.json 中指定。
• options：用於控制指令的行為。

2. 重要選項

• --affected：只執行當前分支上受影響的 package。
• --cache-dir <path>：指定文件系統的快取目錄。
• --concurrency <number | percentage>：設定任務執行的最大並發數量，預設為 10。
• --continue：遇到錯誤後是否繼續執行任務。
• --cwd <path>：指定工作目錄。
• --dry / --dry-run：顯示會執行哪些任務，而不實際執行它們。
• --filter <string>：篩選要執行的目標，可以根據 package、目錄或 Git 提交篩選。
• --force：忽略快取，重新執行所有任務。
• --parallel：忽略任務依賴圖，並行執行任務。
• --profile：生成 Chrome Tracing 格式的運行追蹤，用於性能分析。
• --summarize：生成 JSON 檔案，包含運行的元數據，如受影響的 package 和執行的任務。

3. 篩選與組合範例

• turbo run build --filter={.apps/*}[HEAD^1]：執行所有 apps 子目錄中，自上次提交後有變更的 package。
• turbo run build --filter=docs --filter=web：執行 docs 和 web package 的 build 任務。

4. 併發控制

• turbo run build --concurrency=50%：以 50% 的 CPU 使用率並發執行任務。
• turbo run test --concurrency=5：限制同時執行 5 個測試任務。

5. 常見使用情境

• 使用 --dry 可以查看即將執行的任務而不真正執行，這對於除錯和優化很有幫助。
• 使用 --filter 可以針對具體 package 或目錄進行精細篩選，特別是當需要針對特定變更進行編譯或測試時。
• --profile 是追蹤性能的好工具，特別是對於大型 monorepo。

6. 範例程式碼

要在當前分支上執行受影響的 build、lint 和測試任務，可以使用以下指令：

turbo run build lint test --affected

當要排除某個特定的 package 並進行構建時，使用以下範例：

turbo run build --filter=./apps/* --filter=!./apps/admin

7. 預設與選項行為

• 預設情況下，Turbo 會嘗試並行執行任務，使用 --parallel 可以進一步控制這種行為。
• --force 允許忽略現有快取，強制重新執行任務。

8. 進階選項

• --global-deps <file glob>：指定全局文件系統依賴的文件模式，這對 .env 文件或影響多個 package 的文件很有用。

範例：

turbo run build --global-deps=".env" --global-deps=".eslintrc"

• --graph <file type>：生成當前任務圖的圖像文件（支援 svg、png、jpg 等格式）。如果沒有提供文件名，將會輸出 .dot 格式的圖形。

範例：

turbo run build test lint --graph=my-graph.svg

• --log-order <option>：設置日誌輸出的順序。選項包括：
  • stream：當日誌可用時立即顯示。
  • grouped：按任務分組顯示日誌。
  • auto：由 Turbo 根據環境自動決定。

範例：

turbo run build --log-order=stream

• --log-prefix <option>：控制日誌行前綴格式。選項包括：
  • prefix：強制為日誌加上 <package>:<task> 前綴。
  • none：不使用任何前綴。
  • auto：Turbo 自動決定是否加上前綴。

範例：

turbo run dev --log-prefix=none

9. 快取相關選項

• --no-cache：不快取任務結果，強制所有任務都重新執行。

範例：

turbo run dev --no-cache

• --remote-only：只使用遠端快取，忽略本地快取。

範例：

turbo run build --remote-only

10. 其他常見選項

• --token 和 --team：這些選項主要用於配置遠端快取時提供身份驗證憑證，例如 Vercel 的遠端快取。使用 --token 指定 bearer token，--team 指定遠端快取的團隊。

範例：

turbo run build --team=my-team --token=xxxxxxxxxxxxxxxxx

11. 執行時期 UI 控制

• --ui <option>：指定輸出 UI 顯示格式。可接受的選項包括 stream 和 tui。
• --verbosity：控制日誌的詳細級別。可選擇 -v（info）、-vv（debug）、-vvv（trace）。

範例：

turbo run build --verbosity=2

12. 錯誤處理與容錯

• --continue：默認情況下，當一個任務出現錯誤時，Turbo 會停止執行後續任務。使用 --continue 可以讓 Turbo 遇到錯誤時繼續執行其他任務，但最終 Turbo 會返回執行中出現的最高錯誤碼。

範例：

turbo run build --continue

13. 使用範例

• 在開發過程中，只需要執行發生變更的 package 的任務，可以使用 --affected：

  turbo run build lint test --affected
  

• 若要針對某個特定分支的變更進行比對並執行任務，透過設置 TURBO_SCM_BASE 與 TURBO_SCM_HEAD 來覆寫 Git 的比對基準：

  TURBO_SCM_BASE=development turbo run build --affected
  TURBO_SCM_HEAD=my-feature-branch turbo run build --affected
  

14. 最佳實踐

• 在 CI/CD 管道中，建議使用 turbo run 命令來確保一致性和性能最佳化。
• 在本地開發中，可以直接使用 turbo 簡化命令，例如 turbo build lint check-types 和 turbo run build lint check-types 是相同的命令。

watch

重點整理：

這裡介紹了 turbo watch 指令的用法，該指令會基於代碼變更自動重新執行任務。turbo watch 具有依賴感知能力，會按照 turbo.json 中配置的順序重新執行任務。這裡介紹了 persistent（長時間執行）任務的相關概念和使用限制。

1. 指令基本格式

turbo watch [tasks]

• tasks：要監聽並重新執行的任務。
• turbo watch 是依賴感知的，因此會按照 turbo.json 中的依賴順序執行。

2. 持續執行（Persistent）任務

• 長時間運行的任務（persistent）：標記為 "persistent": true 的任務不會退出，這意味著它們無法作為其他任務的依賴項。turbo watch 不會重新執行這些持續運行的任務。
• 若你的腳本（如 next dev）具備依賴監聽功能，則不需要使用 turbo watch，只需將任務標記為 "persistent": true 即可。

3. 無依賴感知的持續任務

• 一些工具不具備對依賴項的熱重載功能。在這種情況下，應將任務設為非持續性的，讓 turbo watch 在偵測到依賴變更時重新啟動任務。

4. 限制

• 快取：使用 turbo watch 執行任務時，所有的快取操作都會被禁用。
• 任務輸出：如果任務會生成被提交到版本控制的文件，可能會導致 Watch Mode 進入無限循環，因為文件變更會觸發任務重新執行。建議將這些輸出文件排除在 Git 之外，以避免此問題。

5. 範例程式碼

要監聽並重新執行 build 和 test 任務：

turbo watch build test

當你有持續執行的任務（例如 next dev），應將其設為 persistent 並使用內建的依賴監聽，而不是依賴 turbo watch：

"tasks": {
  "dev": {
    "persistent": true
  }
}

6. Watch 模式中的依賴處理

• 依賴感知的持續任務：如果你的腳本有內建的依賴監聽功能（例如 next dev），那麼你不需要依賴 turbo watch 來重新執行任務，因為腳本會自動監聽依賴的變更並進行必要的操作。在這種情況下，應該將任務設為 "persistent": true，讓任務長期運行。

範例：

"tasks": {
  "dev": {
    "persistent": true
  }
}

• 無依賴感知的持續任務：對於那些不支援熱重載或無法感知依賴變更的工具，你可能會想使用 turbo watch。但這類工具無法檢測依賴項的變更，因此應該將任務標記為非持續性的，讓 turbo watch 在偵測到依賴變更時自動重啟任務。

7. 無限循環問題及解決方案

在 Watch 模式中，當任務產生會導致文件變更時，可能會觸發這些變更，從而導致任務再次執行，這可能會導致無限循環。

為了解決這個問題：

• 避免提交輸出文件：如果任務的輸出文件會被提交到 Git 中，建議將這些文件從版本控制中排除，這樣可以避免由於文件變更觸發無限循環。

範例：

.gitignore
/output-folder/*

• Watch 模式的邏輯：turbo watch 使用文件哈希來避免無限循環的發生，但這並不是萬無一失的，因此推薦將任務輸出從版本控制中移除以減少風險。

8. 快取與持續任務

當使用 turbo watch 時，所有的快取操作會被禁用，因為持續運行的任務需要立即響應文件變更而不依賴快取結果。因此，在監控模式下不會生成或使用任何快取。

9. 使用範例

• 假設你有一個 build 任務和一個持續運行的 dev 任務，想要監聽代碼變更並重新執行 build，而 dev 任務保持長期運行。可以這樣配置：

"tasks": {
  "build": {
    "dependsOn": ["^build"]
  },
  "dev": {
    "persistent": true
  }
}

並使用以下指令啟動監控：

turbo watch build

這樣 build 會在文件變更時重新執行，而 dev 任務則持續運行，不受影響。

prune

重點整理：

這裡介紹了 turbo prune 指令，該指令用於為指定的目標 package 生成一個部分 monorepo，並將結果輸出到一個名為 out 的目錄中。這對於精簡項目依賴和減少包大小非常有用，特別是當你只需要針對某個子應用或 package 進行構建時。

1. 指令基本格式

turbo prune [package]

• package：要生成部分 monorepo 的目標 package 名稱。

2. 執行結果

turbo prune 會生成以下內容：

• 完整的內部 package 源代碼：所有構建目標 package 所需的內部依賴包。
• 修剪過的 lockfile：包含構建目標 package 所需的部分 lockfile。
• 根目錄的 package.json 副本。

3. 範例

假設你的項目結構如下：

package.json
pnpm-lock.yaml
apps/
  admin/
  frontend/
packages/
  scripts/
  shared/
  ui/
  utils/

執行以下指令：

turbo prune frontend

會生成一個 out 目錄，包含精簡後的工作區，僅針對 frontend 應用進行構建。

生成後的結構如下：

package.json
pnpm-lock.yaml (partial)
apps/
  frontend/
packages/
  shared/
  ui/

4. 選項

• --docker：默認為 false。此選項會調整輸出目錄，以便更容易配合 Docker 的最佳實踐和層快取機制。輸出結果將分為兩個文件夾：
  • json：包含修剪過的 package.json 文件。
  • full：包含完整的內部 package 源代碼。

範例：

turbo prune frontend --docker

生成後的結構如下：

pnpm-lock.yaml (partial)
full/
  apps/
  packages/
json/
  package.json (from repo root)
  apps/
    frontend/package.json
  packages/
    shared/package.json
    ui/package.json

• --out-dir ：默認輸出目錄為 ./out。此選項允許你自定義輸出目錄的位置。

範例：

turbo prune frontend --out-dir=./custom-output

生成的結果將位於 ./custom-output 目錄中。

LS

重點整理：

這篇文章介紹了 turbo ls 指令，它用於列出 monorepo 中的 package。該指令可以列出整個倉庫中的所有 package，或只列出指定的 package，並顯示相關的詳細資訊。

1. 指令基本格式

turbo ls [package(s)] [flags]

• package(s)：要列出的特定 package 名稱（可選）。
• flags：可用的選項標誌，用於過濾或格式化輸出。

2. 列出所有 package

• 如果不指定 package，turbo ls 會列出整個倉庫中的所有 package，並包含以下資訊：
  • package 管理器
  • package 數量
  • 所有 package 的名稱和目錄

範例：

turbo ls

3. 列出指定的 package

• 如果只想列出一個或多個指定的 package，則會顯示：
  • package 名稱
  • package 目錄
  • 內部依賴
  • 所有任務

範例：

turbo ls web @repo/ui

4. 選項

• --affected：僅列出當前分支中受影響的 package。預設情況下，它會比較 main 和 HEAD 之間的變更，可以使用環境變數來更改比較基準。

範例：

TURBO_SCM_BASE=development turbo ls --affected

• --output ：指定輸出格式，支援 json 和 pretty（預設）。json 格式特別適合於需要進一步處理輸出數據的場景。

範例：

turbo ls --output=json